%% Long tables, matrices, and arrays
% by Jaromir Benes
%
% This m-file shows some of the features and bug fixes relating to long
% tables, matrices and arrays. First, not only tables but also matrices and
% arrays can be now ``long'' meaning they can stretch over multiple pages.
% Second, you can place a one-row note at the foot of each of the mutliple
% pages (except the last one), e.g. to indicate that the table continues;
% this is a feature requested in Issue 15. Third, you can customise the
% format of captions, e.g. titles and subtitles.
%
% Note that using |'long'|=true in tables, matrices and arrays requires the
% LaTeX longtable package to be available in your TeX distribution.

%% Housekeeping

clear;
close all;
home;
irisrequired 8.20111003;

%% Create artificial data that will be reported
% 
% Create a tseries object, a large matrix, and a large cell array combining
% numbers and text. These are use in the report below to create a table
% object, a matrix object, and an array object.

% Create a tseries object. The tseries will be repeated a large number of
% times in a table.
x = tseries(1:10,@rand);

% Create a matrix with a larger number or rows. The matrix will be reported
% as a matrix object.
C = rand(70,3);

% Create a 50-by-5 cell array with mixed content. The cell array will be
% reported as an array object.
s = {'Some text',1,2,pi,'Some more text'};
s = repmat(s,50,1);

%% Start new report

r = report.new();

%% Add long table
%
% Because we create 45 lines in the table it will stretch over multiple
% lines. For a multipage table to be displayed properly when typeset in
% LaTeX we need to set |'long'|=true <?long?>. We place a footnote
% ``---continued'' <?longfoot?> aligned right <?longfootposition?> at the
% bottom of each page (except the last one).


r.table('Table','range',1:10, ...
    'long',true, ... %?long?
    'longfoot','---continued', ... %?longfoot?
    'longfootposition','right'); %?longfootposition?

    for i = 1 : 45
        r.series('Some data',x);
    end

%% Add long matrix
%
% Note that we can now give the matrix a long title (wider than the matrix
% itself), and the matrix columns are still properly formatted -- this is a
% fix to Issue 32.
%
% * <?format?> Note that you can format the footnote using LaTeX commands.
% In that case, you must enclose them in curly braces, otherwise they will
% be displayed literally.

title = 'Matrix with a long title -- longer than the width of the matrix';

r.matrix(title,C, ...
    'rownames=',{'first','second','third','etc.'}, ...
    'long=',true,'longfoot=','{\bfseries\color{red} continued}'); %?format?

%% Add a long array
%
% Arrays (unlike matrices) combine both numbers and text stored in a cell
% array.

r.pagebreak();

r.array('Combine text and numbers in an array',s, ...
    'long=',true,'longfoot=','{\itshape continued}');

%% Figures with formatted title and subtitle (caption)
%
% Tables, matrices, arrays, and figures may have captions consisting of a
% title (first line) and an optional subtitle (second line). If you enter
% as the first input argument a single non-empty text string, only a title
% is displayed. If you enter a cell array with two non-empty strings, both
% a title and a subtitle are displayed. Furthermore, you can use the
% |'captionTypeface'| option to format the text using standard LaTeX
% commands.

r.pagebreak();

r.figure({'Title','Subtitle'}, ...
    'captiontypeface=',{'\large\bfseries\color{red}','\color{blue}'}, ...
    'figureoptions=',{'defaultlinelinewidth=',1.5});
    r.graph('Graph');
        r.series('',x);

%% Publish report to PDF
%
% Compile the report into a PDF named |'report_long_tables.pdf'|. The
% |open| command to open the PDF <?open?> may not work on some systems.

r.publish('report_long_tables.pdf');

open report_long_tables.pdf; %?open?

%% Help on IRIS functions used in this m-file
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help report
%    help report/new
%    help report/table
%    help report/matrix
%    help report/figure
%    help report/pagebreak
%    help report/publish
%    help tseries
%    help tseries/tseries
